/*********************************************************
@file

@author J. Di Mattina

@brief Interface for c-realize library.

This file describes the interface for the c-realize 
library. This allows 
*********************************************************/
#ifndef CRZ_H
#define CRZ_H

#ifdef __cplusplus
extern "C"
{
#endif

/* local includes */
#include "Crz_Types.h"

/*********************************************************
 Crz_Serialize
*//**
@brief Create a serialized data buffer.

The c-realize library creates a data format string which
is used as input to this function for packing messages
described in the .cr files.

The memory allocation for the buffer is handled by the
library, so a NULL buffer should be passed in.

example:

.cr file
@code
struct MyStruct
{
    uint32_t a;
    uint8_t b;
    repeated uint16_t c;
}

message MyMessage
{
    MyStruct a;
    uint32_t b;
}
@endcode

.h file:
@code
#define GET_MYMESSAGE_DESC(desc) \ 
  *desc = "{41*2}4"

typedef struct MyStruct
{
    uint32_t a;
    uint8_t b;
    uint16_t *c;
    uint32_t cSize;
}
@endcode

.c file:
@code
Crz_Result result;
MyStruct s;
uint32_t t;
char *buf = NULL;
char *desc;

// genereate description
GET_MYMESSAGE_DESC(desc);

// call the one size fits all serealization
result = Crz_Serialize(buf, desc, s, t);
@endcode

The end result is buf being filled with a serialized version
of the data structure described in the .h file.

@param [out] buf    Buffer to store serialized data
@param [in]  fmt    Format string descibing the vararg
@param [in]  ...    Vararg of items to pack

@return CRZ_SUCCESS on success,
        corrosponding error code on failure.
**********************************************************/
Crz_Result
Crz_Serialize(char **buf, char *fmt, ...);

/*********************************************************
 Crz_Deserialize
*//**
@brief Unpack a serialized data buffer.

The c-realize library uses the same data format string 
created for serialization as input to this function for 
unpacking messages described in the .cr files.

example:

.cr file
@code
struct MyStruct
{
    uint32_t a;
    uint8_t b;
    repeated uint16_t c;
}

message MyMessage
{
    MyStruct a;
    uint32_t b;
}
@endcode

.h file:
@code
#define GET_MYMESSAGE_DESC(desc) \ 
  *desc = "{41*2}4"

typedef struct MyStruct
{
    uint32_t a;
    uint8_t b;
    uint16_t *c;
    uint32_t cSize;
}
@endcode

.c file:
@code
Crz_Result result;
MyStruct s = {0};
uint32_t t;
char *buf = ...
char *desc;

// genereate description
GET_MYMESSAGE_DESC(desc);

// call the one size fits all deserealization
result = Crz_Deserialize(buf, desc, &s, &t);
@endcode

The end result is the variables described in the .h file being
fully populated with data from the serialized buffer.

@param [in]  buf    Serialized buffer to unpack
@param [in]  fmt    Format string descibing the vararg
@param [out] ...    Vararg of items to place unpacked data

@return CRZ_SUCCESS on success,
        corrosponding error code on failure.
**********************************************************/
Crz_Result
Crz_Deserialize(char *buf, char *fmt, ...);

#ifdef __cplusplus
}
#endif

#endif /* CRZ_H */
